home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / turbovis / hsys12.zip / HELPSYS.DOK < prev    next >
Text File  |  1994-01-31  |  25KB  |  705 lines
  1.  
  2.                                ┬  ┬     ┌─────┤
  3.                                ├──┤ elp └─┐ ys
  4.   ████████████████████████████ ┴  ┴ ├─────┘    ████████████████████████████
  5.                              █▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█
  6.                              ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  7.   ■ HelpSys 1.0
  8.  
  9.   Welcome to HelpSys V1.0, the universal Turbo-Vision helpfile creating 
  10.   utility. HelpSys is a complete help-project-managing utility, that makes 
  11.   it is easy to create, compile, maintain and debug Turbo-Vision style 
  12.   helpfiles.
  13.  
  14.   The included im- and exporters support converting existing helptexts
  15.   and helpfiles into other formats. It's possible to create multi-target 
  16.   helpfile, e.g. to create turbo-vision and windows helpfile in just one 
  17.   project.
  18.   
  19.  
  20.  
  21.   ■ Installation
  22.  
  23.   All HelpSys files should be copied into there own directory. HelpSys 
  24.   will create a subdirectory for each project.
  25.  
  26.  
  27.  
  28.   ■ Introduction
  29.  
  30.   This introduction will show how to create a new project, write helptopics, 
  31.   insert links and add the compiled helpfile into your Turbo-Vision program.
  32.   And some tricks how to optimize the help system.
  33.   
  34.   Attention: You should be familar with programing Turbo Vision and using
  35.              Borland Pascal. 
  36.  
  37.  
  38.   Step 1.) Creating a new project
  39.    Press F10|Project|New. Enter the project name, it must be a valid dos 
  40.    directory name, then enter a short description. HelpSys will open the 
  41.    project window.
  42.  
  43.    
  44.   Step 2.) Creating a help topic
  45.    Use the NEW-Button to create a new topic and its empty helppage. 
  46.    A topic has a symbolic name (i.e. aboutbox) that is refering the 
  47.    helppage, the helpcompiler will generate a pascal context file 
  48.    (i.e. "hcaboutbox = 14;") that can be used in the program source 
  49.    code.
  50.  
  51.    The syntax of a topic name is:
  52.      symbol[=+|=number|=+number][, symbol[=+|=number|=+number][...]]
  53.  
  54.    The symbolic topic name can be any combination of characters and 
  55.    numbers, a topicpage can have multiple topic names. After the topic 
  56.    name a topic number can follow, otherwise HelpSys will assign 
  57.    a topic number during compilation.
  58.  
  59.    More symbolic topic names can be defined by separating them with comma.
  60.  
  61.    I.e.:
  62.  
  63.     foo                   assigns a topic FOO
  64.     baa=100               assigns a topic BAA with page number 100
  65.  
  66.     foo1, baa1, baa2=200  multiple assignment
  67.  
  68.    When the topic is defined, it will appear in the topic list of the
  69.    project window. After placing the focus on the topic and pressing ENTER,
  70.    the topic editor will be opend. It will look something like that:
  71.  
  72.     ; topic created 05.07.93 09:11:37
  73.     ;
  74.     .TOPIC about
  75.     ;
  76.                                      <- up from here it's your job!
  77.      #f{About:about}#!
  78.      ▀▀▀▀▀▀▀▀
  79.  
  80.     This is a about box.
  81.     ^
  82.     │
  83.     └─ this is the first column
  84.  
  85.    The first four lines are created automaticly by HelpSys. They should
  86.    never be changed manualy!!
  87.  
  88.    The format of a help page is quite simple: Any text can be written into
  89.    it.
  90.  
  91.    Some special hints:
  92.     - Text begining in the first column will be wrapped, if it does not fit
  93.       into the window. All adjacent wrappable lines are wrapped as a
  94.       paragraph. To avoid wrapping, text must start with one or more
  95.       blanks.
  96.  
  97.     - Comments can be placed into helptext begining with a ";" in the 
  98.       first column.
  99.       Attention: HelpSys has a special methode to save topics. Due to 
  100.                  that methode, it is not possible to place comments at 
  101.                  the end of a topic file. If a comment must be placed at 
  102.                  the end, please use the ".ENDTOPIC" command to define
  103.                  the end of a topic.
  104.  
  105.     - A compiler keyword is defined by placing a "." into the first column,
  106.       following the keyword.
  107.  
  108.    Links to other pages can be inserted by placing cross references (links)
  109.    into the text. The syntax of a link is:
  110.  
  111.      {link description:topic}
  112.  
  113.    If the link description is equal to the topic, the topic can be omited. 
  114.    The text in the brackets is highlighted by the help viewer. This text 
  115.    can be selected and will take the user to that topic page.
  116.  
  117.    To insert links to already defined pages, the local editor function 
  118.    "insert link" (Alt+F10 or ^k^t) is helpfull...
  119.  
  120.  
  121.   Step 3.) Compiling
  122.    After writing all (or some) pages, the helpfile can be compiled by using
  123.    F10|Run|Compile (F9) or F10|Run|Run (Ctrl+F9). The methode of this
  124.    functions is equal the pascal compiler: COMPILE will compile every time 
  125.    again, RUN will only compile, if it is needed otherwise it will run
  126.    the helpfile at once.
  127.  
  128.    After errorfree compilation HelpSys will parse the pascal symbol file 
  129.    and display a topics list and the page numbers created for the pages.  
  130.    
  131.    Now it's possible to test the helpfile by pressing ENTER after focusing 
  132.    the corrosponding topic. A helpwindow will be opend and the helptext 
  133.    will be displayed. Choose between continuing displaying helptextes 
  134.    from the topics window or switch to the helpwindow and testing the 
  135.    helppage links.
  136.  
  137.    If an error is encounted during compilation, the belonging topic will 
  138.    be opened and the position of the error will be marked and an error 
  139.    description will be shown.
  140.  
  141.  
  142.   Step 4.) Including help into Turbo-Vision
  143.    Hint: The HelpSys package includes a sample program in the EXAMPLE dir. 
  144.          See this for a complete example about usage of help inside your
  145.          Turbo Vision program.  
  146.   
  147.    Including help into Turbo-Vision is quite easy: Each TView object and 
  148.    the descendants own a constant "helpctx". If F1 is pressed, Turbo-Vision 
  149.    will determine by calling the GETHELPCTX-methode the value of the actual 
  150.    helpctx.
  151.  
  152.    So the only thing to do is assigning the constants from the pascal 
  153.    symbol file made by HelpSys to the belonging objects. A dialog would 
  154.    look something like this:
  155.  
  156.      constructor texampledialog.init;
  157.      {...}
  158.      begin
  159.        {...}
  160.        inherited init(r,'Preferences');
  161.        helpctx:=hcpreverences_dialog; {.topic preverences_dialog }
  162.        
  163.        p:=new(Pinputline, Init(R,100)));
  164.        p^.helpctx:=hctheinputlinehelp; {.topic theinputlinehelp }
  165.        insert(p);
  166.  
  167.        {...}
  168.        p:=new(Pbutton, Init(R,'Buttontext',cmok,bfdefault)));
  169.        p^.helpctx:=hcbuttonhelp; {.topic buttonhelp }
  170.        insert(p);
  171.  
  172.        r.assign(01,06,49,07);
  173.        p:=new(PCheckboxes, Init(R,
  174.            NewSItem('a Tcheckboxs field',
  175.            NewSItem('a Tcheckboxs field',
  176.            NewSItem('a Tcheckboxs field',
  177.            NewSItem('a Tcheckboxs field',Nil)))));
  178.        p^.helpctx:=hc1000;
  179.        insert(p);
  180.  
  181.        SelectNext(False);
  182.      end;
  183.  
  184.    TCheckboxes and TRadiobuttons will give back "helpnumber" for the first
  185.    item, "helpnumber+1" for the next item and so one. This is very nice, if
  186.    help is needed for each item, but mostly it is not usefull. To deal with
  187.    this problem, there is only ONE solution:
  188.  
  189.      function tsetupdialog.gethelpctx;
  190.      Var tmp : word;
  191.      begin
  192.        tmp:=inherited gethelpctx;
  193.        case tmp of
  194.          hc1000..hc1010-1 : tmp:=hchelpforcheckboxes;
  195.        end;
  196.        gethelpctx:=tmp;
  197.      end;
  198.  
  199.    Attention: The way of defining a multi-topic line will not work. It
  200.               might work most times, but is not sure to assume, that
  201.               HelpSys generates consecutive topic numbers.
  202.  
  203.               (It will not. HelpSys will try to create consecutive
  204.                numbers, but it also will try to fill gaps. It won't work,
  205.                neither TVHC nor HelpSys can do that job. So its better to
  206.                be one the sure side....)
  207.                
  208.    If help is needed for every item, I suggest the following workaround:
  209.                
  210.      function tsetupdialog.gethelpctx;
  211.      Var tmp : word;
  212.      begin
  213.        tmp:=inherited gethelpctx;
  214.        case tmp of
  215.          hc1000+00 : tmp:=hc_help_for_item1;
  216.          hc1000+01 : tmp:=hc_help_for_item2;
  217.          hc1000+02 : tmp:=hc_he